sphinxdocs: add typedef directive for documenting user-defined types #2300
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This adds support for documenting user-defined Starlark "types". Starlark doesn't have
user-defined types as a first-class concept, but an equivalent can be done by using
struct
with lambdas and closures. On the documentation side, the structure of theseobjects can be shown by have a module-level struct with matching attributes.
On the Sphinx side of things, this is simple to support (and the functionality was largely
already there): it's just having a directive with other directives within it (this
is the same way other languages handle it).
On the Starlark side of things, its a bit more complicated. Stardoc can process a
module-level struct, but essentially returns a list of
(dotted_name, object_proto)
,and it will only include object types it recognizes (e.g. functions, providers, rules, etc).
To work within this limitation, the proto-to-markdown converter special cases the name
"TYPEDEF" to indicate a typedef. Everything with the same prefix is then treated as
a member of the typedef and nested within the generated typedef directive. Conveniently,
because the "TYPEDEF" object is a function, it can then include that in the output
and we get "class doc" functionality for free.
This is mostly motivated by converting rules_testing to use sphinxdocs. While rules_python
has a couple user-define types (e.g. the depset/runfiles/PyInfo builders),
rules_testing has dozens of such types, which makes it untenable to hand-write docs
describing them all. Today, rules_testing is already mostly following the format sphinxdocs
proscribes to generate its at https://rules-testing.readthedocs.io/en/latest/api/index.html,
and it's worked pretty well.